## A.4. Methods Common to All Handles

The following methods can be used by all types of DBI handles:

err |

    $rv = $h->err;

Returns the native database engine error code from the last driver method called. The code is typically an integer, but you should not assume that.

The DBI resets `$h->err` to `undef` before most DBI method calls, so the value has only a short lifespan. Also, most drivers share the same error variables across all their handles, so calling a method on one handle will typically reset the error on all the other handles that are children of that driver.

If you need to test for individual errors and have your program be portable to different database engines, then you'll need to determine what the corresponding error codes are for all those engines, and test for all of them.

errstr |

    $str = $h->errstr;

Returns the native database engine error message from the last driver method called. This has the same lifespan issues as the `err` method described above.

state |

    $str = $h->state;

Returns an error code in the standard SQLSTATE five-character format. Note that the specific success code `00000` is translated to `0` (false). If the driver does not support SQLSTATE (and most don't), then state will return `S1000` (General Error) for all errors.

trace |

    $h->trace($trace_level);
    $h->trace($trace_level, $trace_filename);

DBI trace information can be enabled for a specific handle (and any future children of that handle) by setting the trace level using the `trace` method.

Trace level 1 is best for a simple overview of what's happening. Trace level 2 is a good choice for general-purpose tracing. Levels 3 and above (up to 9) are best reserved for investigating a specific problem, when you need to see "inside" the driver and DBI. Set `$trace_level` to `0` to disable the trace.

The trace output is detailed and typically very useful. Much of the trace output is formatted using the `neat` function, so strings may be edited and truncated.

Initially, trace output is written to `STDERR`. If `$trace_filename` is specified, then the file is opened in append mode and all trace output (including that from other handles) is redirected to that file. Further calls to `trace` without a `$trace_filename` do not alter where the trace output is sent. If `$trace_filename` is undefined, then trace output is sent to `STDERR` and the previous trace file is closed.

See also the `DBI-`>`trace` method for information about the `DBI_TRACE` environment variable.

trace_msg |

    $h->trace_msg($message_text);
    $h->trace_msg($message_text, $min_level);

Writes `$message_text` to the trace file if `trace` is enabled for `$h` or for the DBI as a whole. Can also be called as `DBI-` >`trace_msg($msg)`. See `trace`.

If `$min_level` is defined, then the message is output only if the trace level is equal to or greater than that level. `$min_level` defaults to `1`.

func |

    $h->func(@func_arguments, $func_name);

The `func` method can be used to call private non-standard and non-portable methods implemented by the driver. Note that the function name is given as the last argument.

This method is not directly related to calling stored procedures. Calling stored procedures is currently not defined by the DBI. Some drivers, such as `DBD::Oracle`, support it in non-portable ways.

See driver documentation for more details.

Copyright © 2001 O'Reilly & Associates. All rights reserved.